<!--"$Id: 2.3.html,v 1.4 2007/05/17 18:17:18 bostic Exp $ (Sleepycat) $Date: 2007/05/17 18:17:18 $"-->
<html>
<head>
<title>The Berkeley DB Package: Interface Changes introduced in DB 2.3.0</title>
<meta name="description" content="DB: A database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods">
</head>
<body bgcolor=white>

<h3 align=center>Interface Changes introduced in DB 2.3.0:</h3>

<ol>

<li>
The DB 2.3 btree access method has been enhanced to optionally support
retrieval by record number.
This functionality is based on a new DB_INFO flag, DB_RECNUM.
If the btree is created using this flag, applications may retrieve
records in the tree by record number,
using the DB_SET_RECNO flag to either the dbp-&gt;get() or cursor-&gt;c_get()
interfaces.
This is another additional cursor-&gt;c_get() flag, DB_GET_RECNO which
returns the record number of the record referenced by the cursor.
<p>
<font color=red>
Adding this feature required a change to the underlying btree database format.
For this reason, databases created under previous versions of DB cannot
be read by this release of DB, and vice versa.
</font>
If you have a support contract with Sleepycat Software, please contact
us for further information and assistance in migrating applications and
databases from previous releases of DB to this release.
<p>
See
db_open(3)
and
db_cursor(3)
for more information, as well as the example program examples/ex_btrec.c.

<p><li>
In previous versions of the DB library, additions or deletions into recno
(fixed and variable-length record) databases would automatically renumber
all records logically after the add/delete point.
This behavior is no longer the default behavior as of DB version 2.3.
<p>
The new default behavior is that deleting records does not cause subsequent
records to be renumbered, and it is an error to attempt to add new records
between records already in the database.
Attempting to retrieve deleted keys using either of the dbp-&gt;get() or
cursor-&gt;c_get() functions will return DB_KEYEMPTY.
The historic behavior is still available, based on a new DB_INFO flag,
DB_RENUMBER.
Applications depending on the historic recno access method semantics should
specify the DB_RENUMBER flag, no other change should be necessary.
<p>
In previous versions of the DB library, adding a record more than one
logical record past the current last record in the recno database caused
the creation of the intermediate missing records as existing records with
zero-length data.
While the intermediate missing records are still logically created in
DB 2.3, it is an error to attempt to retrieve them, and the get() and
c_get() functions will return DB_KEYEMPTY.
<p>
In previous versions of the DB library, attempting to retrieve a deleted
record <b>using the same cursor with which it was deleted</b> returned
DB_NOTFOUND.
For consistency with the new recno access method functionality,
such attempts now return DB_KEYEMPTY.
<p>
See
db_open(3)
and
db_cursor(3)
for more information.
<br><font color=red>
These changes are NOT transparent to applications.
</font>

<p><li>
A new flag, DB_APPEND, has been added to the db-&gt;put(3) function in
DB 2.3.
This flag is applicable only to the recno access method.
It permits applications to append to the database without knowing how
many records are in it or the current last record number.
The DB example program examples/ex_tpcb has been modified to use this
functionality.
<p>
See
db_open(3)
for more information.

<p><li>
An additional argument has been added to the memp_fopen(3) function
in DB 2.3.
The mpool functions must be able to uniquely identify files in order
that multiple processes sharing a file will correctly share its
underlying pages.  Normally, the mpool functions use the file's device
and inode numbers for this purpose. On some filesystems, for example,
FAT or NFS, file device and
inode numbers are not necessarily unique across system reboots.
To support applications wanting to maintain a shared memory buffer pool
across system reboots, where the pool contains pages from files stored
on such filesystems, it is now possible to specify a unique file identifier
to the memp_fopen() call, which the memory pool functions will then use to
identify shared files.
The DB access method functions have been modified to use this functionality,
and DB databases in 2.3 will work transparently on such filesystems.
<p>
See
db_mpool(3)
for more information.
<br><font color=red>
This change is NOT transparent to applications using the db_mpool(3)
interfaces directly.
</font>

<p><li>
The interface to the DB access method stat function (dbp-&gt;stat()) has been
changed.
Per-thread statistics are no longer returned, only statistics for the entire
database are returned.
In addition, the stat function has been changed to take an additional
``flags'' parameter.
The only legal value for this parameter in DB 2.3 is DB_RECORDCOUNT,
which causes the stat function to return a count of records in the tree
without collecting other statistics.
<p>
A number of additional items of information have been added to the
information returned by the stat function,
notably database configuration flags and other information normally
specified to the
db_open(3)
function when the database is created.
<p>
See
db_stat(1)
and
db_open(3)
for more information.
<br><font color=red>
This change is NOT transparent to applications.
</font>

<p><li>
A number of new configuration options have been added to the
db_load(1)
utility, allowing databases to be dumped and reloaded in different
configurations.
See
db_load(1)
for more information.

<p><li>
The C++ API for DB has been reworked, and is now believed to be fairly
close to its final form.
There are still no manual pages for the C++ API, although we expect to
have them together and released within a couple of weeks.
<p>
The C++ files and directories in the source distribution are:
<p>
<table border>
<tr>
<td>db/cxx/</td>
<td>C++ API</td>
</tr><tr>
<td>db/examples_cxx/</td>
<td>The example programs recoded in C++.</td>
</tr><tr>
<td>db/include/cxx_int.h</td>
<td>Internal C++ include file.</td>
</tr><tr>
<td>db/include/db_cxx.h</td>
<td>External C++ include file.</td>
</tr>
</table>
<p>
C++ support is automatically built on Win32.  To configure it under UNIX,
specify <b>--enable-cxx</b> as a configuration argument (see the file
<b>db/build.unix/README</b> for more information).

</ol>

</body>
</html>
